package com.wg.db.repository.entity;

import java.io.Serializable;
import java.util.List;

/**
 * 实体仓库接口，定义实体相关的核心CRUD操作
 *
 * @param <K> 主键类型（需实现Serializable，如Long、String）
 * @param <B> 实体对应的Bean类型（数据库持久化对象）
 * @param <E> 业务实体类型（实现IEntity<B>）
 * @author 少爷123
 */
public interface IEntityRepository<K extends Serializable, B, E extends IEntity<B>> {

    /**
     * 根据主键查询实体（同步）
     *
     * @param entityId 主键ID
     * @return 实体对应的Bean对象（不存在返回null）
     */
    B getById(K entityId);

    /**
     * 根据组ID查询实体列表（同步）
     *
     * @param groupId 组ID（业务分组标识）
     * @return 符合条件的Bean列表（无数据返回空列表）
     */
    List<B> getByGroupId(Serializable groupId);

    /**
     * 查询所有实体（同步）
     *
     * @return 所有实体的Bean列表（无数据返回空列表）
     */
    List<B> getAll();

    /**
     * 根据自定义SQL查询实体列表（同步）
     *
     * @param sql 自定义SQL语句（需确保安全性，避免SQL注入）
     * @return 符合条件的Bean列表（无数据返回空列表）
     */
    List<B> getBySql(String sql);

    /**
     * 保存或更新实体（同步/异步）
     * <p>
     * 逻辑：若实体主键存在则更新，否则插入新记录
     *
     * @param entity 业务实体对象（需包含有效主键）
     */
    void saveOrUpdate(E entity);

    /**
     * 批量保存或更新实体（同步/异步）
     * <p>
     * 逻辑：过滤无效实体后，批量执行保存或更新
     *
     * @param entities 业务实体列表（过滤null后处理）
     */
    void batchSaveOrUpdate(List<E> entities);

    /**
     * 删除实体（同步/异步）
     *
     * @param entity 业务实体对象（需包含有效主键）
     */
    void delete(E entity);

    /**
     * 批量删除实体（同步/异步）
     *
     * @param entities 业务实体列表（过滤null后处理）
     */
    void batchDelete(List<E> entities);

    /**
     * 关闭仓库资源（如释放数据库连接、停止异步线程）
     */
    void shutdown();

    /**
     * 获取待处理操作数量（仅异步仓库有效）
     *
     * @return 异步缓冲区中待处理操作的数量
     */
    int pendingSize();
}